﻿sample.suff                package:unknown                R Documentation

SUFICIÊNCIA AMOSTRAL PARA ESTIMATIVAS DE DIVERSIDADE GENÉTICA

Description:

     Função para avaliar se, dado o número de indivíduos diplóides amostrados,
	 o esforço amostral foi suficiente para inferir a diversidade genética de 
	 populações, a partir de marcadores microssatélites genotipados. Há três
     opções para a estimativa de diversidade genética:heterozigosidade esperada,
	 observada ou a riqueza alélica. A função retorna um gráfico de rarefação
	 com a média estimativa de diversidade genética simulada em função do tamanho 
	 amostral da população (podendo ou não incluir o intervalo de confiança das estimativas).
	 Note que o tempo para executar a função sample.suff dependerá do número de simulações
	 definido pelo usuário (nsim), sendo que quanto maior nsim, mais tempo a função
     demorará para terminar sua execução.	 
	 
Usage:

     sample.suff (dados, col.ID, col.pop, col.loci, na.code=NA, IC.plot=TRUE, 
	              gen.div=c("He","Ho","Ar"), nsim=1000)

Arguments:

    dados: data frame com um indivíduo por linha e um locus por coluna, com alelos 
		   separados por /. Além disso, data frame deve ter uma coluna com identificação
		   dos indivíduos e outra com identificação das populações.
    col.ID: número da coluna com identificação dos indivíduos 
		   (deve ser um número inteiro maior que 0).
  	col.pop: número da coluna com identificação da população a qual os indivíduos pertencem
        	(deve ser um número inteiro maior que 0).
  	col.loci: intervalo das colunas correspondentes aos loci microssatélite genotipados 
	         (deve ser um número inteiro maior que 0). Note que a função foi elaborada 
			  para espécies diplóides. Portanto, cada loco deve conter dois alelos.
  	na.code: código utilizado para valores faltantes (Default = NA; neste caso, valores 
	         faltantes no data frame dados não recebem nenhum valor ou código). Para evitar 
			 conflitos com o R, não utilizar "NA" como código para dados faltantes.
  	IC.plot: vetor lógico que indica se intervalos de confiança devem ou não ser plotados 
	        (Default = TRUE).
  	gen.div: estimativa de diversidade genética a ser calculada, podendo ser heterozigosidade 
	         esperada e observada (He e Ho, respectivamente) e riqueza alélica (Ar).
  	nsim: número de simulações (Default = 1000).  

Details:

    Veja a seção Examples desta página de ajuda para obter um exemplo de data frame a ser 
	utilizado como argumento dados da função.

Value:

    A função retorna:
	(1) Gráfico de rarefação com estimativa de diversidade genética simulada em função do 
	    tamanho amostral da população (podendo ou não incluir o intervalo de confiança das 
		estimativas). Neste gráfico, cada população é representada por uma cor diferente.
		As linhas representam a média da estimativa de diversidade genética para cada população 
		nos cenários simulados e a área sombreada o intervalos de confiança referentes às 
		estimativas.
    (2) Uma lista contendo:
	    comp1: data frame com estimativa de diversidade genética observada para as populações 
		comp2: data frame com média e intervalos de confiança superior e inferior da estimativa 
		       de diversidade gética para cada população em cenários simulados com diferentes 
			   números de indivíduos. 

Warning:

    (1) Para evitar conflitos com o R, não utilizar na.code = "NA" 
	(2) Caso argumentos da função sejam inseridos incorretamente, a função não será executada,
	    retornando mensagens de erro.
	(3) O tempo para executar a função sample.suff dependerá do número de simulações definido 
	    pelo usuário (nsim), sendo que quanto maior nsim, mais tempo a função demorará para terminar 
		sua execução. Sugere-se, portanto, testar previamente a executabilidade da função com baixo 
		nsim (<20). Uma vez atestada positivamente sua execução, definir nsim com valor maior ou 
		igual a 1000. Caso nsim seja menor que 1000, função executará, mas retornará um warning 
		"Um número baixo de simulações pode afetar a confiabilidade dos resultados!"
	(4) A função sample.suff precisa do pacote 'adegenet' (Jombart 2008) para executar. Portanto,
	    sua instalação é necessária antes da execução de sample.suff
	
Author(s):

    Marianne Azevedo Silva
	E-mail: azevedosilva.m@gmail.com

References:

    Jombart T. (2008) adegenet: a R package for the multivariate analysis of genetic markers. 
	Bioinformatics 24: 1403-1405. DOI:10.1093/bioinformatics/btn129
	
	Mori GM, Zucchi MI, Souza AP (2015) Multiple-Geographic-Scale Genetic Structure of Two 
	Mangrove Tree Species: The Roles of Mating System, Hybridization, Limited Dispersal and 
	Extrinsic Factors. PLoS ONE 10: e0118710. DOI:10.1371/journal.pone.0118710

See Also:

    pacote adegenet para compreender algumas funções incorporadas na função sample.suff

Examples:

    # Exemplo de estruturação de dataset. Este exemplo é um subconjunto do dataset disponível no trabalho 
	# de Mori et al. 2015 PLoS ONE 10(2): e0118710.
	  print(data.frame(ID=c("AsAJU01","AsAJU02","AsAJU03"), pop=rep("Braganca-PA",3), locus01=c("221/221","223/223","225/219"),
          locus02=c("150/150","148/150","148/148"), locus03=c("213/213","","227/233")),row.names=F)
	# Exemplos de uso da função (nos dois exemplos, nsim foi deixado como 10 para que o exemplo execute 
	# mais rapidamente. Para uma análise com maior confiabilidade nsim deve ser maior ou igual a 1000
	# Exemplo1:
	# Gerar gáfico de rarefação, com intervalos de confiança, para as estimativas de heterozigosidade esperada
	# em cenários simulados 
	# Carregar dados. Esses dados também são oriundos do dataset disponível no trabalho 
	# de Mori et al. 2015 PLoS ONE 10(2): e0118710
	dados <- read.table("dados-exemplo.txt", header = T,sep="\t",as.is = F)
    # Ver estrutura dos dados
	str(dados)
	# Executar função sample.suff
	sample.suff(dados, col.ID=1, col.pop=2, col.loci=3:14, na.code=NA, IC.plot=TRUE, gen.div="He", nsim=10)
	# Exemplo2:
	# Gerar gáfico de rarefação, sem intervalos de confiança, para as estimativas de riqueza alélica
	# em cenários simulados 
	# Executar função sample.suff
	sample.suff(dados, col.ID=1, col.pop=2, col.loci=3:14, IC.plot=FALSE, gen.div="Ar", nsim=10)

